home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / opxms114.zip / OPXMS.TXT < prev   
Text File  |  1992-04-07  |  17KB  |  443 lines
  1. ;
  2. ;-------------------------------------------------------------------
  3. !TOPIC 1 OpXms
  4. The OpXms unit contains a variety of routines for working with extended
  5. memory. It allows you to determine whether or not XMS memory is installed
  6. and, if so, how much is currently available. You can allocate and deallocate
  7. extended memory.
  8.  
  9. This unit also has routines for working with the High Memory Area (HMA).
  10. To use the HMA, routines are also provided to enable, disable, and query the
  11. state of the CPU's A20 line, which must be enabled in order to use
  12. the HMA.
  13.  
  14. Allocated extended memory blocks may be locked. This assures that they will
  15. not be moved by the XMS memory manager. This unit contains routines to lock,
  16. unlock, and get information about allocated extended memory blocks.
  17.  
  18. Some XMS memory managers support routines to allocate and free Upper Memory
  19. Blocks (UMB). UMBs are areas of memory located above the 640K of DOS
  20. accessable memory and below the 1 megabyte boundary. This memory is generally
  21. only accessable under 386 extended memory managers. This unit contains
  22. routines to allocate and free UMBs.
  23.  
  24. For further information on XMS memory, it is recommended that you read the
  25. documentation that accompanies Microsoft's HIMEM.SYS XMS driver. Also, the
  26. Addison Wesley book "Extending MS-DOS" contains an excellent discussion of XMS
  27. memory.
  28.  
  29.   0015AllocateExtMem             0022AllocUpperMemBlock       0002Declarations
  30.   0005Error codes                0016FreeExtMem               0023FreeUpperMemBlock
  31.   0020GetHandleInfo              0010GlobalDisableA20         0009GlobalEnableA20
  32.   0012LocalDisableA20            0011LocalEnableA20           0018LockExtMemBlock
  33.   0017MoveExtMemBlock            0013QueryA20                 0014QueryFreeExtMem
  34.   0008ReleaseHMA                 0021ResizeExtMemBlock        0007RequestHMA
  35.   0019UnlockExtMemBlock          0024XmsErrorString           0006XmsInstalled
  36. ;
  37. ;-------------------------------------------------------------------
  38. !TOPIC 2 Declarations
  39. !NOINDEX
  40. OPXMS provides the following types and variables:
  41.  
  42.   0003ExtMemPtr           0004XmsControl
  43.  
  44. ;
  45. ;-------------------------------------------------------------------
  46. !TOPIC 3 ExtMemPtr
  47. !NOINDEX
  48. type
  49.   ExtMemPtr      =
  50.     record
  51.       case Boolean of
  52.         False : (RealPtr : Pointer);
  53.         True  : (ProtectedPtr : LongInt);
  54.     end;
  55.  
  56. A variant record used to specify pointers to either conventional or extended
  57. memory. In conventional memory, pointers are normal Segment:Offset dword
  58. pointers. In protected memory, linear (LongInt) pointers are used. This type
  59. is used only for the 0017MoveExtMemBlock function.
  60. ;
  61. ;-------------------------------------------------------------------
  62. !TOPIC 4 XmsControl
  63. !NOINDEX
  64. var
  65.   XmsControl       : Pointer;
  66.  
  67. Stores a pointer to the XMS control procedure. This is intended primarily for
  68. internal use.
  69. ;-------------------------------------------------------------------
  70. !TOPIC 5 Error codes
  71. !NOINDEX
  72. The following is a list of the error code constants interfaced by the
  73. 0001OPXMS unit:
  74.  
  75.   FuncNotImplemented   = $80; {function is not implemented}
  76.   VDiskDeviceDetected  = $81; {a VDISK compatible device found}
  77.   A20Error             = $82; {an A20 error occurred}
  78.   GeneralDriverError   = $8E; {general driver error}
  79.   UnrecoverableError   = $8F; {unrecoverable driver error}
  80.   HmaDoesNotExist      = $90; {high memory area does not exist}
  81.   HmaAlreadyInUse      = $91; {high memory area already in use}
  82.   HmaSizeTooSmall      = $92; {size requested less than /HMAMIN}
  83.   HmaNotAllocated      = $93; {high memory area not allocated}
  84.   A20StillEnabled      = $94; {A20 line is still enabled}
  85.   AllExtMemAllocated   = $A0; {all extended memory is allocated}
  86.   OutOfExtMemHandles   = $A1; {extended memory handles exhausted}
  87.   InvalidHandle        = $A2; {invalid handle}
  88.   InvalidSourceHandle  = $A3; {invalid source handle}
  89.   InvalidSourceOffset  = $A4; {invalid source offset}
  90.   InvalidDestHandle    = $A5; {invalid destination handle}
  91.   InvalidDestOffset    = $A6; {invalid destination offset}
  92.   InvalidLength        = $A7; {invalid length}
  93.   OverlapInMoveReq     = $A8; {overlap in move request}
  94.   ParityErrorDetected  = $A9; {parity error detected}
  95.   BlockIsNotLocked     = $AA; {block is not locked}
  96.   BlockIsLocked        = $AB; {block is locked}
  97.   LockCountOverflowed  = $AC; {lock count overflowed}
  98.   LockFailed           = $AD; {lock failed}
  99.   SmallerUMBAvailable  = $B0; {a smaller upper memory block is avail}
  100.   NoUMBAvailable       = $B1; {no upper memory blocks are available}
  101.   InvalidUMBSegment    = $B2; {invalid upper memory block segment}
  102.  
  103. The routine 0024XmsErrorString can be used to translate an error code
  104. returned by an OPXMS function into an error message.
  105. ;
  106. ;-------------------------------------------------------------------
  107. !TOPIC 6 XmsInstalled
  108. !NOINDEX
  109. function 0001OpXms.XmsInstalled : Boolean;
  110.  
  111. Returns True if an XMS memory manager is installed.
  112. ;
  113. ;-------------------------------------------------------------------
  114. !TOPIC 7 RequestHMA
  115. !NOINDEX
  116. function 0001OpXms.RequestHMA(Bytes : Word) : Byte;
  117.  
  118. Request the High Memory Area (HMA). Bytes is amount of memory if TSR or
  119. device driver, or $FFFF if application program. Possible return codes:
  120.  
  121.   $00 successful
  122.   $80 if the function is not implemented
  123.   $81 if a VDISK device is detected
  124.   $90 if the HMA does not exist
  125.   $91 if the HMA is already in use
  126.   $92 if Bytes is less than the /HMAMIN= parameter
  127.  
  128. See also:
  129.   0008ReleaseHMA
  130. ;
  131. ;-------------------------------------------------------------------
  132. !TOPIC 8 ReleaseHMA
  133. !NOINDEX
  134. function 0001OpXms.ReleaseHMA : Byte;
  135.  
  136. Release the High Memory Area. Possible return codes:
  137.  
  138.   $00 successful
  139.   $80 if the function is not implemented
  140.   $81 if a VDISK device is detected
  141.   $90 if the HMA does not exist
  142.   $93 if the HMA was not allocated
  143.  
  144. See also:
  145.   0007RequestHMA
  146. ;
  147. ;-------------------------------------------------------------------
  148. !TOPIC 9 GlobalEnableA20
  149. !NOINDEX
  150. function 0001OpXms.GlobalEnableA20 : Byte;
  151.  
  152. Attempt to enable the A20 line. Should be used only by programs that
  153. have control of the HMA. Possible return codes:
  154.  
  155.   $00 successful
  156.   $80 if the function is not implemented
  157.   $81 if a VDISK device is detected
  158.   $82 if an A20 error occurs
  159.  
  160. See also:
  161.   0010GlobalDisableA20              0011LocalEnableA20
  162.   0012LocalDisableA20               0013QueryA20
  163. ;
  164. ;-------------------------------------------------------------------
  165. !TOPIC 10 GlobalDisableA20
  166. !NOINDEX
  167. function 0001OpXms.GlobalDisableA20 : Byte;
  168.  
  169. Attempt to disable the A20 line. Possible return codes:
  170.  
  171.   $00 successful
  172.   $80 if the function is not implemented
  173.   $81 if a VDISK device is detected
  174.   $82 if an A20 error occurs
  175.   $94 if the A20 line is still enabled
  176.  
  177. See also:
  178.   0009GlobalEnableA20               0011LocalEnableA20
  179.   0012LocalDisableA20               0013QueryA20
  180. ;
  181. ;-------------------------------------------------------------------
  182. !TOPIC 11 LocalEnableA20
  183. !NOINDEX
  184. function 0001OpXms.LocalEnableA20 : Byte;
  185.  
  186. Attempt to enable the A20 line. Should be used only by programs that
  187. need direct access to extended memory. Possible return codes:
  188.  
  189.   $00 successful
  190.   $80 if the function is not implemented
  191.   $81 if a VDISK device is detected
  192.   $82 if an A20 error occurs
  193.  
  194. See also:
  195.   0010GlobalDisableA20              0009GlobalEnableA20
  196.   0012LocalDisableA20               0013QueryA20
  197. ;
  198. ;-------------------------------------------------------------------
  199. !TOPIC 12 LocalDisableA20
  200. !NOINDEX
  201. function 0001OpXms.LocalDisableA20 : Byte;
  202.  
  203. Attempt to disable the A20 line. Possible return codes:
  204.  
  205.   $00 successful
  206.   $80 if the function is not implemented
  207.   $81 if a VDISK device is detected
  208.   $82 if an A20 error occurs
  209.   $94 if the A20 line is still enabled
  210.  
  211. See also:
  212.   0010GlobalDisableA20              0009GlobalEnableA20
  213.   0011LocalEnableA20                0013QueryA20
  214. ;
  215. ;-------------------------------------------------------------------
  216. !TOPIC 13 QueryA20
  217. !NOINDEX
  218. function 0001OpXms.QueryA20 : Byte;
  219.  
  220. Checks to see if the A20 line is physically enabled. Possible return codes:
  221.  
  222.   $00 A20 line disabled
  223.   $01 A20 line enabled
  224.   $80 if the function is not implemented
  225.   $81 if a VDISK device is detected
  226.  
  227. See also:
  228.   0010GlobalDisableA20               0009GlobalEnableA20
  229.   0011LocalEnableA20                 0012LocalDisableA20
  230. ;
  231. ;-------------------------------------------------------------------
  232. !TOPIC 14 QueryFreeExtMem
  233. !NOINDEX
  234. function 0001OpXms.QueryFreeExtMem(var TotalFree,
  235.                                LargestBlock : Word) : Byte;
  236.  
  237. Return the amount of total free extended memory in TotalFree, and the Size
  238. of the largest free block of extended memory in LargestBlock. Both values
  239. are specified in number of kilobytes. Possible function results:
  240.  
  241.   $00 successful
  242.   $80 if the function is not implemented
  243.   $81 if a VDISK device is detected
  244.   $A0 if all extended memory is allocated
  245. ;
  246. ;-------------------------------------------------------------------
  247. !TOPIC 15 AllocateExtMem
  248. !NOINDEX
  249. function 0001OpXms.AllocateExtMem(SizeInK : Word;
  250.                               var XmsHandle : Word) : Byte;
  251.  
  252. Allocate a block of extended memory SizeInK kilobytes in size, returning
  253. the XMS handle in XmsHandle. Possible function results:
  254.  
  255.   $00 successful
  256.   $80 if the function is not implemented
  257.   $81 if a VDISK device is detected
  258.   $A0 if all extended memory is allocated
  259.   $A1 if all extended memory handles are in use
  260.  
  261. See also: 0016FreeExtMem
  262. ;
  263. ;-------------------------------------------------------------------
  264. !TOPIC 16 FreeExtMem
  265. !NOINDEX
  266. function 0001OpXms.FreeExtMem(XmsHandle : Word) : Byte;
  267.  
  268. Free a previously allocated block of extended memory. XmsHandle is the XMS
  269. handle returned by the previous call to 0015AllocateExtMem.
  270. Possible function results:
  271.  
  272.   $00 successful
  273.   $80 if the function is not implemented
  274.   $81 if a VDISK device is detected
  275.   $A2 if XmsHandle is invalid
  276.   $AB if XmsHandle is currently locked
  277.  
  278. See also: 0015AllocateExtMem
  279. ;
  280. ;-------------------------------------------------------------------
  281. !TOPIC 17 MoveExtMemBlock
  282. !NOINDEX
  283. function 0001OpXms.MoveExtMemBlock(BlockLength : LongInt;
  284.                                SourceHandle : Word;
  285.                                SourcePtr : ExtMemPtr;
  286.                                DestHandle : Word;
  287.                                DestPtr : ExtMemPtr) : Byte;
  288.  
  289. Move a block of memory. Intended primarily for moving data to and from
  290. extended memory and conventional memory. Can also move memory from
  291. extended to extended and conventional to conventional. BlockLength must
  292. always be an even number. Memory areas may overlap ONLY if SourcePtr is at
  293. a lower address than DestPtr. If SourceHandle is 0, then SourcePtr is
  294. interpreted as a normal segment:offset dword pointer. If SourceHandle is
  295. non-zero, then the SourcePtr is interpreted as a 32 bit linear offset into
  296. the extended memory associated with SourceHandle. The same is true for
  297. DestHandle and DestPtr. This routine does NOT require that the A20 line be
  298. enabled. Extended memory blocks used as SourcePtr or DestPtr need not be
  299. locked before calling this routine (although they may be locked). Possible
  300. function results:
  301.  
  302.   $00 successful
  303.   $80 if the function is not implemented
  304.   $81 if a VDISK device is detected
  305.   $82 if an A20 error occurs
  306.   $A3 if SourceHandle is invalid
  307.   $A4 if SourcePtr is invalid
  308.   $A5 if DestHandle is invalid
  309.   $A6 if DestPtr is invalid
  310.   $A7 if BlockLen is invalid
  311.   $A8 if SourcePtr and DestPtr contain an invalid overlap
  312.   $A9 if a memory parity error occurs
  313. ;
  314. ;-------------------------------------------------------------------
  315. !TOPIC 18 LockExtMemBlock
  316. !NOINDEX
  317. function 0001OpXms.LockExtMemBlock(XmsHandle : Word;
  318.                                var LockedBlock : ExtMemPtr) : Byte;
  319.  
  320. Locks an extended memory block and returns its base address as a 32 bit
  321. linear address. Locked extended memory blocks are guaranteed not to move.
  322. The LockedBlock address is valid only while the block is locked. Locked
  323. extended memory blocks should be unlocked as soon as possible. It is
  324. not necessary to lock a block before calling 0017MoveExtMemBlock. A count of
  325. the number of locks is maintained by the XMS memory manager and can be
  326. retrieved with the 0020GetHandleInfo function. Possible function results:
  327.  
  328.   $00 successful
  329.   $80 if the function is not implemented
  330.   $81 if a VDISK device is detected
  331.   $A2 if XmsHandle is invalid
  332.   $AC if the block's lock count overflows
  333.   $AD if the lock fails
  334.  
  335. See also:  0019UnlockExtMemBlock
  336. ;
  337. ;-------------------------------------------------------------------
  338. !TOPIC 19 UnlockExtMemBlock
  339. !NOINDEX
  340. function 0001OpXms.UnlockExtMemBlock(XmsHandle : Word) : Byte;
  341.  
  342. Unlocks an extended memory block. Any 32 bit linear addresses in use
  343. obtained by calling 0018LockExtMemBlock are invalid after
  344. UnlockExtMemBlock is called. Possible function results:
  345.  
  346.   $00 successful
  347.   $80 if the function is not implemented
  348.   $81 if a VDISK device is detected
  349.   $A2 if XmsHandle is invalid
  350.   $AC if the block's lock count overflows
  351.   $AA if the block is not locked
  352.  
  353. See also:  0018LockExtMemBlock
  354. ;
  355. ;-------------------------------------------------------------------
  356. !TOPIC 20 GetHandleInfo
  357. !NOINDEX
  358. function 0001OpXms.GetHandleInfo(XmsHandle : Word;
  359.                              var LockCount    : Byte;
  360.                              var HandlesLeft  : Byte;
  361.                              var BlockSizeInK : Word) : Byte;
  362.  
  363. Return information about an extended memory handle. The lock count for
  364. this handle, the number of XMS handles left, and the size in kilobytes of
  365. this handle are returned. To retrieve the 32 bit linear address of this
  366. handle, you must call 0018LockExtMemBlock. Possible function results:
  367.  
  368.   $00 successful
  369.   $80 if the function is not implemented
  370.   $81 if a VDISK device is detected
  371.   $A2 if XmsHandle is invalid
  372. ;
  373. ;-------------------------------------------------------------------
  374. !TOPIC 21 ResizeExtMemBlock
  375. !NOINDEX
  376. function 0001OpXms.ResizeExtMemBlock(XmsHandle : Word;
  377.                                  NewSizeInK : Word) : Byte;
  378.  
  379. Attempts to resize the memory block associated with XmsHandle. The
  380. extended memory block must be unlocked. If the NewSizeInK is bigger than
  381. the previous size, then all data is preserved. If it is smaller, then all
  382. data beyond the end of the new block size is lost. Possible function results:
  383.  
  384.   $00 successful
  385.   $80 if the function is not implemented
  386.   $81 if a VDISK device is detected
  387.   $A0 if all extended memory is allocated
  388.   $A1 if all extended memory handles are in use
  389.   $A2 if XmsHandle is invalid
  390.   $AB if the block is locked
  391.  
  392. See also:  0015AllocateExtMem
  393. ;
  394. ;-------------------------------------------------------------------
  395. !TOPIC 22 AllocUpperMemBlock
  396. !NOINDEX
  397. function 0001OpXms.AllocUpperMemBlock(SizeInParas : Word;
  398.                                   var SegmentBase : Word;
  399.                                   var Size        : Word) : Byte;
  400.  
  401. Allocates an upper memory block (UMB). If insufficient memory is available in
  402. upper memory blocks, then the size of the largest free upper memory block is
  403. returned in Size. If this functions succeeds, then SegmentBase contains
  404. the segment of the allocated upper memory block. Upper memory blocks are
  405. paragraph aligned (the offset is always 0). By definition, UMBs are located
  406. below the 1 meg address boundary. Therefore the A20 line need not be enabled
  407. to access the memory in a UMB. There are no restrictions on using this memory
  408. in DOS calls or pointing ISRs into this memory.
  409.  
  410. This function is not implemented by most 286 XMS drivers. It is implemented by
  411. most 386 products like QEMM and 386^MAX. Possible function results:
  412.  
  413.   $00 successful
  414.   $80 if the function is not implemented
  415.   $B0 if a smaller UMB is available
  416.   $B1 if no UMBs are available
  417.  
  418. See also:  0023FreeUpperMemBlock
  419. ;
  420. ;-------------------------------------------------------------------
  421. !TOPIC 23 FreeUpperMemBlock
  422. !NOINDEX
  423. function 0001OpXms.FreeUpperMemBlock(SegmentBase : Word) : Byte;
  424.  
  425. Frees a previously allocated upper memory block.
  426. Possible function results:
  427.  
  428.   $00 successful
  429.   $80 if the function is not implemented
  430.   $82 if SegmentBase does not refer to a valid UMB
  431.  
  432. See also:  0022AllocUpperMemBlock
  433. ;
  434. ;-------------------------------------------------------------------
  435. !TOPIC 24 XmsErrorString
  436. !NOINDEX
  437. function 0001OpXms.XmsErrorString(ErrorCode : Byte) : String;
  438.  
  439. Return a string indicating reason for the error.
  440.  
  441. See also:  0005Error codes
  442.  
  443.